<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Map Tool Tutorial &mdash; GeoExt v1.1</title>
    <link rel="stylesheet" href="../_static/geoext.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '1.1',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="shortcut icon" href="../_static/favicon.ico"/>
    <link rel="top" title="GeoExt v1.1" href="../index.html" />
    <link rel="up" title="Tutorials" href="index.html" />
    <link rel="next" title="Vector Data Tutorial" href="remote-features-tutorial.html" />
    <link rel="prev" title="Layer Tree Tutorial" href="layertree-tutorial.html" />
    
    
    
    
    

  </head>
  <body>
    <div class="header">
        <div class="wrap">
            <h1 id="logo"><a href="../index.html">GeoExt</a></h1>
            <ul id="top-nav">
                <li class="first"><a href="../docs.html">Documentation</a></li>
                <li><a href="../examples.html">Examples</a></li>
                <li><a href="../downloads.html">Download</a></li>
                <li><a href="http://trac.geoext.org/">Development</a></li>
            </ul>
            <div id="searchbox">
                <form class="search" action="../search.html" method="get">
                    <input id="searchbox-query" type="text" name="q" size="25" value="Search &hellip;" tabindex="3" onblur="if(this.value=='') this.value='Search &hellip;';" onfocus="if(this.value=='Search &hellip;') this.value='';" />
                    <input id="searchbox-submit" type="image" value="Search" src="../_static/img/search_icon_green.png" />
                    <input type="hidden" name="check_keywords" value="yes" />
                    <input type="hidden" name="area" value="default" />
                </form>
            </div>
        </div>
    </div>

    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li><a href="../index.html">GeoExt</a> &raquo;</li>
          <li><a href="index.html" accesskey="U">Tutorials</a> &raquo;</li>
        <li><a href="#">Map Tool Tutorial</a></li>
      </ul>
    </div>

      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3><a href="../index.html">Table Of Contents</a></h3>
            <ul>
<li><a class="reference external" href="#">Map Tool Tutorial</a><ul>
<li><a class="reference external" href="#openlayers-controls">OpenLayers Controls</a></li>
<li><a class="reference external" href="#extjs-buttons">ExtJS Buttons</a></li>
<li><a class="reference external" href="#there-can-be-only-one">There Can Be Only One</a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="layertree-tutorial.html"
                                  title="previous chapter">Layer Tree Tutorial</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="remote-features-tutorial.html"
                                  title="next chapter">Vector Data Tutorial</a></p>
        </div>
      </div>


    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="map-tool-tutorial">
<h1>Map Tool Tutorial<a class="headerlink" href="#map-tool-tutorial" title="Permalink to this headline">¶</a></h1>
<p>Okay, so now you know how to <a class="reference external" href="mappanel-tutorial.html"><em>add a map to a web page</em></a>
and load some data into it. Your users can drag and zoom to their hearts&#8217;
content. You even followed the <a class="reference external" href="layertree-tutorial.html"><em>Layer Tree Tutorial</em></a> so they could switch
between different datasets. (You did follow that tutorial, right?) But now you
want to do more than just view some pretty pictures. You want to let your users
analyze data, or get more info about particular features on your map, or just
draw things. Basically, you want to give them some <strong>tools</strong>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This tutorial makes heavy use of the OpenLayers mapping library.  If
you&#8217;re not familiar with it, you might want to take a look at the
<a class="reference external" href="../primers/openlayers-primer.html"><em>Primer: OpenLayers</em></a> before moving forward.</p>
</div>
<div class="section" id="openlayers-controls">
<h2>OpenLayers Controls<a class="headerlink" href="#openlayers-controls" title="Permalink to this headline">¶</a></h2>
<p>In <a class="reference external" href="http://openlayers.org/">OpenLayers</a>, these tools for interacting with a
map are called <tt class="docutils literal"><span class="pre">Controls</span></tt>. For the purposes of this tutorial, we&#8217;ll just
stick to the <tt class="docutils literal"><span class="pre">Measure</span></tt> control, a handy little tool that lets you draw a line
on the map and tells you its length in real-world units.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">The OpenLayer API documentation for a comprehensive listing of standard controls.</p>
</div>
</div>
<div class="section" id="extjs-buttons">
<h2>ExtJS Buttons<a class="headerlink" href="#extjs-buttons" title="Permalink to this headline">¶</a></h2>
<p>While OpenLayers <tt class="docutils literal"><span class="pre">Control</span></tt>s provide a number of excellent ways of
interacting with maps, they have only limited support for actually manipulating
the controls; ie, choosing which tool to use and providing user feedback about
which tool is active. ExtJS provides a richer array of options for managing
tools. Here is the idiomatic way to create an <tt class="docutils literal"><span class="pre">Ext.Button</span></tt> which activates and
deactivates an OpenLayers <tt class="docutils literal"><span class="pre">Control</span></tt>, and stays depressed while the control
is active:</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">control</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Control</span><span class="p">.</span><span class="nx">Measure</span><span class="p">(</span><span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Handler</span><span class="p">.</span><span class="nx">Path</span><span class="p">,</span> <span class="p">{</span>
    <span class="nx">eventListeners</span><span class="o">:</span> <span class="p">{</span>
        <span class="nx">measure</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">evt</span><span class="p">)</span> <span class="p">{</span>
            <span class="nx">alert</span><span class="p">(</span><span class="s2">&quot;The measurement was &quot;</span> <span class="o">+</span> <span class="nx">evt</span><span class="p">.</span><span class="nx">measure</span> <span class="o">+</span> <span class="nx">evt</span><span class="p">.</span><span class="nx">units</span><span class="p">);</span>
        <span class="p">}</span>
    <span class="p">}</span>
<span class="p">});</span>

<span class="nx">mapPanel</span><span class="p">.</span><span class="nx">map</span><span class="p">.</span><span class="nx">addControl</span><span class="p">(</span><span class="nx">control</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">button</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Ext</span><span class="p">.</span><span class="nx">Button</span><span class="p">({</span>
    <span class="nx">text</span><span class="o">:</span> <span class="s1">&#39;Measure Things&#39;</span><span class="p">,</span>
    <span class="nx">enableToggle</span><span class="o">:</span> <span class="kc">true</span><span class="p">,</span>
    <span class="nx">handler</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">toggled</span><span class="p">){</span>
        <span class="k">if</span> <span class="p">(</span><span class="nx">toggled</span><span class="p">)</span> <span class="p">{</span>
            <span class="nx">control</span><span class="p">.</span><span class="nx">activate</span><span class="p">();</span>
        <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
            <span class="nx">control</span><span class="p">.</span><span class="nx">deactivate</span><span class="p">();</span>
        <span class="p">}</span>
    <span class="p">}</span>
<span class="p">});</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">Button</span></tt> can be added to an ExtJS toolbar or to a panel, in whatever
layout we choose. For example, you could add the button to a <tt class="docutils literal"><span class="pre">MapPanel</span></tt>&#8216;s
top toolbar:</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">mapPanel</span><span class="p">.</span><span class="nx">getTopToolbar</span><span class="p">().</span><span class="nx">addButton</span><span class="p">(</span><span class="nx">button</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="there-can-be-only-one">
<h2>There Can Be Only One<a class="headerlink" href="#there-can-be-only-one" title="Permalink to this headline">¶</a></h2>
<p>In general, when you have multiple tools associated with a map, you want to
avoid having more than one tool active at the same time. It would be somewhat
confusing if the user starts deleting data while he or she is trying to find the
distance from one end of town to the other! Fortunately, ExtJS makes it very
simple to ensure that only one toggle button from a group is toggled at a time,
through the <tt class="docutils literal"><span class="pre">toggleGroup</span></tt> property of the <tt class="docutils literal"><span class="pre">Button</span></tt> object. This is a string
identifying a group of buttons, only one of which can be pressed at a time.
Let&#8217;s extend our example from before, this time adding the option to measure
area instead of length:</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">length</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Control</span><span class="p">.</span><span class="nx">Measure</span><span class="p">(</span><span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Handler</span><span class="p">.</span><span class="nx">Path</span><span class="p">,</span> <span class="p">{</span>
    <span class="nx">eventListeners</span><span class="o">:</span> <span class="p">{</span>
        <span class="nx">measure</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">evt</span><span class="p">)</span> <span class="p">{</span>
            <span class="nx">alert</span><span class="p">(</span><span class="s2">&quot;The length was &quot;</span> <span class="o">+</span> <span class="nx">evt</span><span class="p">.</span><span class="nx">measure</span> <span class="o">+</span> <span class="nx">evt</span><span class="p">.</span><span class="nx">units</span><span class="p">);</span>
        <span class="p">}</span>
    <span class="p">}</span>
<span class="p">});</span>

<span class="kd">var</span> <span class="nx">area</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Control</span><span class="p">.</span><span class="nx">Measure</span><span class="p">(</span><span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Handler</span><span class="p">.</span><span class="nx">Polygon</span><span class="p">,</span> <span class="p">{</span>
    <span class="nx">eventListeners</span><span class="o">:</span> <span class="p">{</span>
        <span class="nx">measure</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">evt</span><span class="p">)</span> <span class="p">{</span>
            <span class="nx">alert</span><span class="p">(</span><span class="s2">&quot;The area was &quot;</span> <span class="o">+</span> <span class="nx">evt</span><span class="p">.</span><span class="nx">measure</span> <span class="o">+</span> <span class="nx">evt</span><span class="p">.</span><span class="nx">units</span><span class="p">);</span>
        <span class="p">}</span>
    <span class="p">}</span>
<span class="p">});</span>

<span class="nx">mapPanel</span><span class="p">.</span><span class="nx">map</span><span class="p">.</span><span class="nx">addControl</span><span class="p">(</span><span class="nx">length</span><span class="p">);</span>
<span class="nx">mapPanel</span><span class="p">.</span><span class="nx">map</span><span class="p">.</span><span class="nx">addControl</span><span class="p">(</span><span class="nx">area</span><span class="p">);</span>

<span class="kd">var</span> <span class="nx">toggleGroup</span> <span class="o">=</span> <span class="s2">&quot;measure controls&quot;</span><span class="p">;</span>

<span class="kd">var</span> <span class="nx">lengthButton</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Ext</span><span class="p">.</span><span class="nx">Button</span><span class="p">({</span>
    <span class="nx">text</span><span class="o">:</span> <span class="s1">&#39;Measure Length&#39;</span><span class="p">,</span>
    <span class="nx">enableToggle</span><span class="o">:</span> <span class="kc">true</span><span class="p">,</span>
    <span class="nx">toggleGroup</span><span class="o">:</span> <span class="nx">toggleGroup</span><span class="p">,</span>
    <span class="nx">handler</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">toggled</span><span class="p">){</span>
        <span class="k">if</span> <span class="p">(</span><span class="nx">toggled</span><span class="p">)</span> <span class="p">{</span>
            <span class="nx">length</span><span class="p">.</span><span class="nx">activate</span><span class="p">();</span>
        <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
            <span class="nx">length</span><span class="p">.</span><span class="nx">deactivate</span><span class="p">();</span>
        <span class="p">}</span>
    <span class="p">}</span>
<span class="p">});</span>

<span class="kd">var</span> <span class="nx">area</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Ext</span><span class="p">.</span><span class="nx">Button</span><span class="p">({</span>
    <span class="nx">text</span><span class="o">:</span> <span class="s1">&#39;Measure Area&#39;</span><span class="p">,</span>
    <span class="nx">enableToggle</span><span class="o">:</span> <span class="kc">true</span><span class="p">,</span>
    <span class="nx">toggleGroup</span><span class="o">:</span> <span class="nx">toggleGroup</span><span class="p">,</span>
    <span class="nx">handler</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">toggled</span><span class="p">){</span>
        <span class="k">if</span> <span class="p">(</span><span class="nx">toggled</span><span class="p">)</span> <span class="p">{</span>
            <span class="nx">area</span><span class="p">.</span><span class="nx">activate</span><span class="p">();</span>
        <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
            <span class="nx">area</span><span class="p">.</span><span class="nx">deactivate</span><span class="p">();</span>
        <span class="p">}</span>
    <span class="p">}</span>
<span class="p">});</span>
</pre></div>
</div>
<p>All right, you&#8217;ve got all you need to add and activate tools to help users get
the most out of your maps.</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
            <li class="right" style="margin-right: 10px">
              <a href="../genindex.html" title="General Index"
                 accesskey="I">index</a></li>
            <li class="right" >
              <a href="../modindex.html" title="Global Module Index"
                 accesskey="M">modules</a> |</li>
            <li class="right" >
              <a href="remote-features-tutorial.html" title="Vector Data Tutorial"
                 accesskey="N">next</a> |</li>
            <li class="right" >
              <a href="layertree-tutorial.html" title="Layer Tree Tutorial"
                 accesskey="P">previous</a> |</li>
        <li><a href="../index.html">GeoExt</a> &raquo;</li>
          <li><a href="index.html" >Tutorials</a> &raquo;</li>
        <li><a href="#">Map Tool Tutorial</a></li>
      </ul>
    </div>

    <div class="footer">
      &copy; Copyright 2009-2010, GeoExt Community.
    </div>
  </body>
</html>